home *** CD-ROM | disk | FTP | other *** search
/ TPUG - Toronto PET Users Group / TPUG Users Group CD / TPUG Users Group CD.iso / AMIGA / (A)TC / (A)TCA.ADF / Scan / scan.readme < prev    next >
Text File  |  1992-07-29  |  18KB  |  378 lines
  1.  
  2.    Program: Scan
  3.  
  4.    Version: 1.0 5/17/92
  5.  
  6.    Utility: Searches twice as fast on hard drives and five times faster
  7.             in ram than the best search programs currently available.
  8.  
  9.             Option to scan selective(wildcard) internal LZH and LHA files
  10.  
  11.             Supports searching for multiple patterns simultaneously
  12.             with little speed degradation.
  13.  
  14.             Option to output whole article when a match is found.
  15.  
  16.             Extensive wildcard support(#?,*,?,[],[^],[-],+,|,&,..).
  17.  
  18.             Optional inverted pattern matching.
  19.  
  20.             Recursive directory scanning.
  21.  
  22.             Support for \x?? and \? in patterns and article separator.
  23.  
  24.             Line search highlights matching words with selectable color.
  25.  
  26.             Freeware.
  27.  
  28.    Tribute: Eternal praise to Jesus for saving my soul and for the wonders
  29.             of God's creation.
  30.  
  31.    Legal:   Copyright ⌐ 1991, 1992 by Walter Rothe
  32.  
  33.             This program is freely distributable, but copyrighted by me. This
  34.             means that you can copy it freely as long as you don't ask for any
  35.             more money than a nominal fee for copying. This program may be
  36.             placed on Public Domain disks, like Fred Fish's library. To
  37.             distribute this program you must include the program,
  38.             documentation, and test files in their original unmodified form.
  39.             This does not preclude compression by archiving programs like
  40.             lharc. This program cannot be used for commercial purposes
  41.             without written permission from the author. The author can not
  42.             be made responsible for any damage which is caused by using
  43.             this program. Derivative works must be released with source along
  44.             with the executable or provisions made to provide the user source,
  45.             if requested. Uploading source to a major US bulletin board system
  46.             within 6 months of the time of the request satisfies this
  47.             requirement. Improvements to this program must include this file,
  48.             with any changes in functionality documented, keeping the
  49.             "Tribute", "Legal", "Author", and "Contact" sections unchanged
  50.             and including an updated "scan.revisions" and "scan.todo" file.
  51.             The example configuration files should also be included.
  52.  
  53.    Command: Scan -[nprt] -[hColor] -[lNumLines] -[wWinSize] -[oOutFile]
  54.    format        -[zLHAWild] SrchFile(s) Pattern
  55.  
  56.                               OR
  57.  
  58.             Scan -f[CnfgFile] -[oOutFile] -[pr] -[zLHAWild] SrchFile(s)
  59.  
  60.                               OR
  61.  
  62.             Scan -a[ipr] [-cColumn] -[sArtSep] -[oOutFile] -[wWinSize]
  63.                  -[zLHAWild] SrchFile(s) Pattern
  64.  
  65.                               OR
  66.  
  67.             Scan -[vx]
  68.  
  69.    Names:   Color       - A two digit number, where the 1st number indicates
  70.                           the color the matching word is highlighted with,
  71.                           and the second is the color the filenames of the
  72.                           files being searched are highlighted with. Currently
  73.                           limited to 0-9.
  74.  
  75.             NumLines    - Number of lines of context information printed
  76.                           around match.
  77.  
  78.             WinSize     - Number of bytes in window. Default 16K bytes.
  79.                           Modulus( WinSize, 4 ) must be 0. There are
  80.                           three buffers, each WinSize long that are swapped.
  81.                           Larger size windows usually increase the speed,
  82.                           except when handling large numbers of small files.
  83.                           Also, the larger the window, the more context
  84.                           information can be printed. Context info is limited
  85.                           to whats in the present and previous buffer. Large
  86.                           article may need a large window to be fully printed
  87.                           out. Currently the WinSize is forced to 16kb
  88.                           whenever the -z option is in effect.
  89.  
  90.             OutFile     - Pathname of file output will be put into.
  91.  
  92.             LHAWild     - Wildcard pattern that is used to determine which
  93.                           internal LHA files are scanned. Only "#?", "*", and
  94.                           "?" wildcards are permitted here. Note that the full
  95.                           internal filename must be matched. Any directories
  96.                           must be included. Some shells expand wildcards on
  97.                           the command line so you may need to enclose the
  98.                           option with quotes. i.e. "-z*.c"
  99.  
  100.             SrchFile(s) - Pathname of file(s) to be searched. Only "#?", "*",
  101.                           and "?" wildcards are permited here. For recursive dir
  102.                           scans, you need only specify the directory pathname.
  103.                           You can optionally add a "/" or "/*.h" to the end of
  104.                           the directory pathname. The command line is limited
  105.                           to 255 chars so if you specify a wildcard pattern and
  106.                           the pathnames of the matching files exceed 255 chars,
  107.                           the last files wont be scanned. To get around this,
  108.                           enclose the wildcard with quotes. i.e. "*.l??"
  109.  
  110.             Pattern     - Pattern to search for. This can include the wildcards
  111.                           "#?", "*", "?", "&", "|", "+", and "..". Refer to
  112.                           the following section on pattern matching. Note that
  113.                           you may need to enclose some of the wildcards in
  114.                           quotes to keep the shell from expanding them. Also,
  115.                           there must be at least 2 consequtive unique non
  116.                           wildcard characters in each pattern between the
  117.                           "|" wildcards. Pattern is case insensitive. For
  118.                           example "sale..d*paint[3i]|paint&prog"
  119.  
  120.             CnfgFile    - Pathname of file containing article separator,
  121.                           column for article separator, inversion flag,
  122.                           window size, and search pattern with each on a
  123.                           separate line, starting in column 1. Note that each
  124.                           pattern between "|"'s appears on a separate line
  125.                           without the "|". There is a maximum of 125 of these.
  126.                           If the "-f" option is not followed with a name,
  127.                           then file S:scan.config is used.
  128.  
  129.             ArtSep      - Article separator. Defaults to "\nArticle". Note
  130.                           that a "\" in the article separator has the same
  131.                           meaning as that in the pattern matching algorithm
  132.                           explained below. An article separator must be 2 or
  133.                           more characters long. For example, "\n\n" is a
  134.                           valid separator and causes a new article to be
  135.                           started with each blank line. Note that some shells
  136.                           require you to specify this as "\\n\\n".
  137.  
  138.    Options:
  139.  
  140.             -a            Article scan. Prints out all articles with matches.
  141.  
  142.             -cColumn      Column article separtor must be in(1..?).
  143.  
  144.             -fCnfgFile    Get parms from config file.
  145.  
  146.             -f            Get parms from s:scan.config.
  147.  
  148.             -hxy          Highlight match with x color and pathname, y color.
  149.  
  150.             -i            Invert matching so nonmatching articles are printed.
  151.  
  152.             -lxx          Line search with xx lines around target printed.
  153.  
  154.             -n            Print line numbers with matched text(slower).
  155.  
  156.             -oOutFile     Send output to file.
  157.  
  158.             -p            Always print file pathnames scanned.
  159.  
  160.             -r            Recursively scan down directories.
  161.  
  162.             -sArtSep      Article separator(def Article).
  163.  
  164.             -t            Truncate output to window width. Only works with -n.
  165.  
  166.             -v            Print version number. Other options nulled.
  167.  
  168.             -wWinSize     Window size(def 16384 bytes). Mod(size,4) must be 0.
  169.  
  170.             -x            Print out more help information. Nulls other options.
  171.  
  172.             -zWildPat     Enabl decomp of .lzh and .lha files with int files
  173.                           matching WildPat.
  174.  
  175.             -z            Enable decompression of all .lzh and .lha files.
  176.  
  177.    Pattern:
  178.    matching
  179.  
  180.             ?           Matches any single character except
  181.  
  182.             [chars]     Match any characters within braces. i.e. [abcxyz]
  183.  
  184.             [c1-c2]     Match any character from c1 to c2. i.e. [a-x]
  185.  
  186.             [^chars]    Match any characters not within the brackets.
  187.  
  188.             \xYY        Matches hex number YY as a character. Note that back
  189.                         slashes are preprocessed by some shells. You may need
  190.                         to put two slashes back to back to prevent this.
  191.  
  192.             \Y          Matches the standard C escape sequence Y
  193.  
  194.             \YYY        Matches the decimal number YYY as a character
  195.  
  196.             |           Finding the pattern on the left or right causes a match
  197.  
  198.             +           Same as |
  199.  
  200.             #?          Pattern on left and right must both match and be in the
  201.                         same word. Match on left must come before one on right.
  202.  
  203.             *           Same as #?
  204.  
  205.             &           Pattern on left and right must both match and be in the
  206.                         same sentence. Match on left must come before match on
  207.                         the right. A sentence is delimited by:
  208.  
  209.                         a) period followed by a space or line feed
  210.                         b) a maximum of OVERLAP(512) characters
  211.                         c) two newline chars with no chars but ">" between them
  212.                         d) start or end of article
  213.                         e) newline before a colon
  214.  
  215.             ..          Pattern on left and right must both match and be in the
  216.                         same article. Order of left and right matches is not
  217.                         important. This is faster than "&". This wildcard is
  218.                         only used during article scans(-a or -f), not line
  219.                         scans.
  220.  
  221.  
  222.    Config:
  223.    format
  224.  
  225.            line 1       Article separator
  226.  
  227.            line 2       Column article separator must be in. 0 -> ignore
  228.  
  229.            line 3       Invert match flag. 1 -> invert match. 0 -> normal
  230.  
  231.            line 4       Window size in bytes. Mod( size, 4 ) must be 0.
  232.  
  233.            line 5..129  Search patterns. There is an implicit "|" between
  234.                         each line. There may be fewer than 125 pattern lines
  235.                         if there are any ".." wildcards on a line. The number
  236.                         of lines is reduced directly by the number of ".."'s.
  237.  
  238.  
  239.    Background:
  240.  
  241.            I wrote "scan" to help minimize the time I spend scanning the
  242.            very large(megabyte) USENET proceedings I download weekly. This
  243.            program scans a file or set of files looking for strings matching a
  244.            user specified pattern(s). It supports the traditional #?, *, ?, and
  245.            [] wildcards, but includes three new ones; "&" and "|" which are
  246.            similar to "*" but work on sentences and articles instead of words
  247.            and ".." which is similar to "&" but is order independent. "Scan"
  248.            can print out the entire text of an article if a match is found
  249.            anywhere in the article. It can search recursively down directories
  250.            and do inverse pattern matching where only articles that don't match
  251.            the pattern are printed out. Due to the size of Usenet proceedings,
  252.            it's desirable to keep them archived in compressed form. Scan
  253.            supports .LZH and .LHA formats with .LHA being significantly faster
  254.            and more dense. You can even selectively scan user specified
  255.            internal .LZH and .LHA files using a wildcard pattern. Finally, up
  256.            to 125 patterns can be scanned for simultaneously, with minimal
  257.            speed degradation.
  258.  
  259.            The fastest search programs I've seen to date are "zgrep" and the
  260.            "csh" search command. "Zgrep has the edge when run out of ram
  261.            but "csh" does better on hard disk searches. "Scan" searches twice
  262.            as fast as "csh" on harddrives and 3 times faster than "zgrep".
  263.            It searches 5 times faster than "zgrep" in ram and 15 times faster
  264.            than "csh" in ram. Search time is about the same for all 3 when
  265.            done off of the floppy.
  266.  
  267.  
  268.    Algorithm:
  269.  
  270.            A preprocessor selects the least repetitive two character
  271.            sub-pattern from each major term of the pattern. An even and an
  272.            odd two character subpattern is selected. This allows 16 bits
  273.            to be processed at a time in the inner loop. These two character
  274.            subpatterns are used to do a parallel Boyer-Moore type search.
  275.            If a match is found with the two char subpattern, the rest of
  276.            the pattern is checked. If the full major term matches, a flag is
  277.            set and other flags examined to see if the full minterm matches.
  278.            If so, another flag is set to cause the article to be printed out.
  279.            A triple buffer approach is used with Matt Dillons asynchronous
  280.            I/O to help speed file reads. Thanks Matt. A special two character
  281.            end of buffer subpattern is put at the end of the buffer so EOF
  282.            wont have to be checked for after each pattern check.
  283.  
  284.  
  285.    Examples:
  286.  
  287.            Searching for sentences with the words "Amiga" and "commercial"
  288.            in them is specified with:
  289.  
  290.                  amiga&commercial | commercial&amiga
  291.  
  292.            If "Amiga" and commercial don't have to be in the same sentence,
  293.            then it can be done with:
  294.  
  295.                  amiga..commercial
  296.  
  297.            To find the paragraphs with the words "truth" and "life" in them
  298.            within the Gospel of John, using the archived new testament on BIX,
  299.            with the "csh" shell, and printing out the internal book names as
  300.            they are scanned:
  301.  
  302.                  scan -aps\\n\\n "-z*john*" biblenew.lha truth..life
  303.  
  304.            This takes about 3 seconds off a harddrive on an A3000.
  305.  
  306.            Note also that to setup an alias in "csh" requires additional
  307.            back slashes:
  308.  
  309.                  alias scankjv "*aa*ab*ac scan -as\\\\n\\\\n"
  310.  
  311.            Note the *aa*ab*ac in the above alias. It is the way you tell "csh"
  312.            not to expand wildcards before passing them to "scan". Up to 3
  313.            arguments, in this case, will not be expanded. The only exception
  314.            to this is the "|" symbol. Since "csh" uses this for piping, you
  315.            have to put quotes around any argument with a "|" in it. You can
  316.            use "+" instead of "|" without quotes.
  317.  
  318.            To find all occurances of "faith" and "healed" in the same sentence
  319.            in the entire new testament, only printing out the names of the
  320.            books with the matches, highlighting the word that matched, and
  321.            printing 3 lines of context on both sides of the match:
  322.  
  323.                  scan -l3 -z biblenew.* faith&healed+healed&faith
  324.  
  325.            The Amiga style wildcard "#?" may be used interchangably with the
  326.            "*" wildcard.
  327.  
  328.  
  329.    Hints:  Search patterns must be at least 2 characters long.
  330.            There must be at least two consequtive unique characters
  331.            within each major term of the pattern. A major term is delimited
  332.            by a "|", "+", or "..". The program will tell you if it cannot
  333.            find unique subpatterns.
  334.  
  335.            There are four distinct command formats of Scan. The 1st is a
  336.            default format which scans for matching lines, not articles.
  337.            The 2nd format has a "-a" in it and scans for articles. The
  338.            3rd has a "-f" in it and also scans for articles, but it gets
  339.            most of its options from a configuration file. The 4th is used
  340.            to print the version or more help information.
  341.  
  342.            Specifying an article separator containing line feeds, can be
  343.            done by adding a "\n". Note that some command line interpreters
  344.            require an extra slash "\\n". For example, to specify a blank
  345.            line as an article separator with csh, use "-s\\n\\n".
  346.  
  347.            Command line options can be grouped together with the exception
  348.            of those having arguments. An option with an argument like "-l"
  349.            must appear with a separate dash or be the last option in a
  350.            dash group.
  351.  
  352.            Some CLI's, along with Scan, limit the command line to 255
  353.            characters. When doing wildcard file matching on the command
  354.            line, large numbers of matching files can cause a command line
  355.            overrun. This is not harmful, but some of the files you expected
  356.            to get scanned, won't be. The solution is to put quotes around
  357.            the wildcards.
  358.  
  359.            The filename pattern matching algorithm is alot faster than the
  360.            one in "csh" and probably other shells. Because of this, it is
  361.            alot faster to do:
  362.  
  363.                  scan "dh0:work/*" xyz
  364.  
  365.            than to do:
  366.  
  367.                  scan dh0:work/* xyz
  368.  
  369.            especially if there are alot of files in the directory.
  370.  
  371.  
  372.    Author: Walter Rothe
  373.  
  374.    Contact: BIX - aimania     OR     2008 Mary St, Carrollton, Tx 75006
  375.  
  376.  
  377.  
  378.